<!DOCTYPE html>
<html lang="en">
<head>

    <!--
      Obviously, used Bootstrap Web site as template.
      Tried to write from scratch but it still looked like bootstrap site, but wasn't that good.
    -->

    <meta charset="utf-8">
    <title>Midao Project</title>
    <meta property="og:title" content="Midao - data oriented umbrella project"/>
    <meta property="og:description"
          content="Midao Project is created to shield Java developer from nuances of vendor implementation and standard boilerplate code.
            Midao JDBC simplifies development with Java JDBC. It is flexible, customizable, and simple/intuitive to use, and provides a lot of functionality"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="">
    <meta name="author" content="">

    <!-- Le styles -->
    <link href="css/bootstrap.css" rel="stylesheet">
    <link href="css/bootstrap-responsive.css" rel="stylesheet">
    <link href="css/docs.css" rel="stylesheet">
    <link href="js/google-code-prettify/prettify.css" rel="stylesheet">

    <!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
    <!--[if lt IE 9]>
    <script src="js/html5shiv.js"></script>
    <![endif]-->

    <!-- Le fav and touch icons -->
    <link rel="apple-touch-icon-precomposed" sizes="144x144" href="ico/apple-touch-icon-144-precomposed.png">
    <link rel="apple-touch-icon-precomposed" sizes="114x114" href="ico/apple-touch-icon-114-precomposed.png">
    <link rel="apple-touch-icon-precomposed" sizes="72x72" href="ico/apple-touch-icon-72-precomposed.png">
    <link rel="apple-touch-icon-precomposed" href="ico/apple-touch-icon-57-precomposed.png">
    <link rel="shortcut icon" href="ico/favicon.png">

</head>

<body data-spy="scroll" data-target=".bs-docs-sidebar">

<!-- Navbar
================================================== -->
<div class="navbar navbar-inverse navbar-fixed-top">
    <div class="navbar-inner">
        <div class="container">
            <button type="button" class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
            </button>

            <div class="nav-collapse collapse">
                <ul class="nav pull-left">

                    <li class="dropdown">
                        <a href="" class="brand" data-toggle="dropdown">Midao Project <i class="icon-chevron-down icon-white caret-chevron-c"></i></a>
                        <ul class="dropdown-menu pull-right">
                            <li class="">
                                <a href="./home.html">Home</a>
                            </li>
                            <li class="">
                                <a href="./news">Blog / news</a>
                            </li>
                            <li class="">
                                <a href="./status.html">Status / future</a>
                            </li>
                            <li class="">
                                <a href="./get-involved.html">Get Involved</a>
                            </li>
                        </ul>
                    </li>

                    <li class="">
                        <a class="brand">Midao JDBC <i class="icon-chevron-right icon-white caret-chevron-c"></i></a>
                    </li>
                    <li class="">
                        <a href="./mjdbc-query.html">Query Execution</a>
                    </li>
                    <li class="active">
                        <a href="./mjdbc-io-handlers.html">IO Handlers</a>
                    </li>
                    <li class="">
                        <a href="./mjdbc-core-handlers.html">Core Handlers</a>
                    </li>
                    <li class="">
                        <a href="./mjdbc-other-features.html">Other features</a>
                    </li>
                </ul>

                <ul class="nav pull-right">
                    <li class="dropdown">
                        <a href="" class="brand" data-toggle="dropdown">Midao Docs <i class="icon-chevron-down icon-white caret-chevron-c"></i></a>
                        <ul class="dropdown-menu pull-right">
                            <li class="">
                                <a href="./mjdbc-presentation.html">Midao JDBC Presentation</a>
                            </li>
                            <li class="">
                                <a href="./mjdbc-getting-started.html">Midao JDBC Getting Started</a>
                            </li>
                        </ul>
                    </li>
                </ul>
            </div>
        </div>
    </div>
</div>

<!-- Subhead
================================================== -->
<header class="jumbotron subhead" id="overview">
    <div class="container">
        <h1>Input/Output Handlers</h1>

        <p class="lead">Overview Input/Output Handlers and how to use them</p>
    </div>
</header>

<div class="container">

    <!-- Docs nav
    ================================================== -->
    <div class="row">
        <div class="span3 bs-docs-sidebar">
            <ul class="nav nav-list bs-docs-sidenav">
                <li><a href="#input-handler"><i class="icon-chevron-right"></i> Input Handlers</a></li>
                <li><a href="#named-input-handler"><i class="icon-chevron-right"></i> |--- Named Input Handlers</a></li>
                <li><a href="#extended-input-handler"><i class="icon-chevron-right"></i> |--- Extended Input Handlers</a></li>
                <li><a href="#query-input-handler"><i class="icon-chevron-right"></i> |--- Query Input Handlers</a></li>
                <li><a href="#output-handler"><i class="icon-chevron-right"></i> Output Handlers</a></li>
                <li><a href="#keyed-output-handler"><i class="icon-chevron-right"></i> |--- Keyed Output Handlers</a></li>
                <li><a href="#base-output-handler"><i class="icon-chevron-right"></i> |--- Base Output Handlers</a></li>
                <li><a href="#lazy-output-handler"><i class="icon-chevron-right"></i> |--- Lazy Output Handlers</a></li>
                <li><a href="#xml-handler"><i class="icon-chevron-right"></i> XML Handlers</a></li>
            </ul>
        </div>
        <div class="span9">

            <!-- Input Handlers
            ================================================== -->
            <section id="input-handler">
                <div class="page-header">
                    <h1>1. Input Handlers</h1>
                </div>

                <p class="lead">For detailed information and description of below handlers - please look at <a href="http://midao.org/mjdbc/javadoc/org/midao/jdbc/core/handlers/input/InputHandler.html">JavaDoc</a>.</p>

                <p><code>InputHandler</code> is responsible for handling input Query parameters: query string, input parameters, parameter values, types, direction and order.</p>

            </section>

            <section id="named-input-handler">
                <div class="page-header">
                    <h2>1.1 NamedInputHandler</h2>
                </div>

                <h3>BeanInputHandler</h3>

                <p><code>BeanInputHandler</code> allows accepting Java Class as source of parameter values</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
Cat cat = new Cat();
			
// initialize cat with data
			
InputHandler input = new BeanInputHandler&ltCat&gt("SELECT ID FROM CATS WHERE AGE = :cat.age AND NAME = :cat.name"
	, cat, "cat");</pre>

                <h3>BeanListInputHandler</h3>

                <p><code>BeanListInputHandler</code> allows accepting List of Java Class as source of parameter values</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
String encodedMultipleParameterQuery = "SELECT * FROM cats FULL JOIN dogs ON cats.owner=dogs.owner WHERE (cats.AGE=:cat.age AND cats.NAME = :cat.name) or (dogs.weight = :dog.weight AND dogs.breed = :dog.breed AND dogs.age = :dog.age)";

Map&ltString, Pet&gt parameterValues = new HashMap&ltString, Pet&gt();
parameterValues.put("cat", this.cat);
parameterValues.put("dog", this.dog);
		
BeanListInputHandler&ltPet&gt inputHandler = new BeanListInputHandler&ltPet&gt(encodedMultipleParameterQuery, parameterValues);</pre>


                <h3>MapInputHandler</h3>

                <p><code>MapInputHandler</code> allows accepting Java Map as source of parameter values</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
String encodedSingleParameterQuery = "SELECT ID FROM CATS WHERE AGE=:cat.age AND NAME = :cat.name";
		  
Map&ltString, Object&gt catMap = new HashMap&ltString, Object&gt() {
		{put("age", 5);put("name", "whiskers");}
};

MapInputHandler inputHandler = new MapInputHandler(this.encodedSingleParameterQuery, this.catMap, "cat");</pre>


                <h3>MapListInputHandler</h3>

                <p><code>MapListInputHandler</code> allows accepting List of Java Map as source of parameter values</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
Map&ltString, Object&gt catMap = new HashMap&ltString, Object&gt() {
		{put("age", 5);put("name", "whiskers");}
};

Map&ltString, Object&gt dogMap = new HashMap&ltString, Object&gt() {
		{put("weight", 17);put("breed", "Blue Lacy");put("age", 3);}
};
		  
Map&ltString, Map&ltString, Object&gt&gt parameterValues = new HashMap&ltString, Map&ltString, Object&gt&gt();
parameterValues.put("cat", this.catMap);
parameterValues.put("dog", this.dogMap);
		
MapListInputHandler inputHandler = new MapListInputHandler(this.encodedMultipleParameterQuery, parameterValues);</pre>

            </section>

            <section id="extended-input-handler">

                <div class="page-header">
                    <h2>1.2 Extended Input Handlers</h2>
                </div>

                <p>Extended Input Handlers have the same core as <a href="http://midao.org/mjdbc-io-handlers.html#named-input-handler">standard named handlers</a>, but unlike the latter - allow to
                    set parameter type inline. Example below.</p>

                <p>For additional information please browse <a href="http://midao.org/mjdbc-io-handlers.html#named-input-handler">Named Input Handlers</a> and <a href="http://midao.org/mjdbc/javadoc/org/midao/jdbc/core/handlers/input/InputHandler.html">JavaDoc</a>.</p>

                <p>Please be careful as currently only "jdbcType" (varchar/integer etc.; types which are listed in <a href="http://midao.org/mjdbc/javadoc/org/midao/jdbc/core/MjdbcTypes.html">MjdbcTypes</a>) and "mode" (in, out, inout; as listed in
                    <a href="http://midao.org/mjdbc/javadoc/org/midao/jdbc/core/handlers/model/QueryParameters.Direction.html">QueryParameters.Direction</a>) are supported.</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
Map&ltString, Object&gt queryParameters = new HashMap&ltString, Object&gt();
queryParameters.put("id", 1);

MapInputHandlerEx input =
               new MapInputHandlerEx(
                    "SELECT name FROM students WHERE id = #{id,jdbcType=INTEGER,mode=in}",
                    queryParameters);

Map&ltString, Object&gt result = runner.query(input, new MapOutputHandler());
</pre>

                <ul>
                    <li><p><code>BeanInputHandlerEx</code></p></li>
                    <li><p><code>BeanListInputHandlerEx</code></p></li>
                    <li><p><code>MapInputHandlerEx</code></p></li>
                    <li><p><code>MapListInputHandlerEx</code></p></li>
                </ul>

            </section>

            <section id="query-input-handler">

                <div class="page-header">
                    <h2>1.3 Query Input Handler</h2>
                </div>

                <h3>QueryInputHandler</h3>

                <p><code>QueryInputHandler</code> allows accepting <code>QueryParameters</code> as source of parameter values</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
QueryParameters parameters = new QueryParameters();

// for MySQL, MariaDB, Oracle
parameters.set("clobIn", "John", Types.CLOB, QueryParameters.Direction.IN);
parameters.set("clobOut", null, Types.CLOB, QueryParameters.Direction.OUT);
		        
parameters.set("blobIn", "Doe", Types.BLOB, QueryParameters.Direction.IN);
parameters.set("blobOut", null, Types.BLOB, QueryParameters.Direction.OUT);

input = new QueryInputHandler("{call TEST_PROC_LARGE(:clobIn, :clobOut, :blobIn, :blobOut)}", parameters);</pre>

                <h3>Spring Handlers</h3>
                <ul>
                    <li><p><code>SpringBeanInputHandler</code></p></li>
                    <li><p><code>SpringBeanListInputHandler</code></p></li>
                    <li><p><code>SpringMapInputHandler</code></p></li>
                    <li><p><code>SpringMapListInputHandler</code></p></li>
                </ul>

                <p>The difference between InputHandlers and Spring Input Handlers is that Spring Handlers are using <code>SpringInputProcessor</code> instead of <code>BaseInputProcessor</code></p>

                <hr class="bs-docs-separator">
            </section>

            <!-- Output Handler
            ================================================== -->
            <section id="output-handler">
                <div class="page-header">
                    <h1>2. Output Handlers</h1>
                </div>
                <p class="lead">For detailed information and description of below handlers - please look at <a href="http://midao.org/mjdbc/javadoc/org/midao/jdbc/core/handlers/output/OutputHandler.html">JavaDoc</a>.</p>

                <p><code>OutputHandler</code> is responsible for handling Query output and converting it into Java Classes</p>

                <hr class="bs-docs-separator">

                <p>Table which would be used for showcasing possibilities of OutputHandlers</p>

                <div class="bs-docs-example">
                    <table class="table">
                        <thead>
                        <tr>
                            <th>#</th>
                            <th>Name</th>
                            <th>Occupation</th>
                            <th>Age</th>
                        </tr>
                        </thead>
                        <tbody>
                        <tr>
                            <td>1</td>
                            <td>Jack</td>
                            <td>Sheriff</td>
                            <td>36</td>
                        </tr>
                        <tr>
                            <td>2</td>
                            <td>Henry</td>
                            <td>Mechanic</td>
                            <td>36</td>
                        </tr>
                        <tr>
                            <td>3</td>
                            <td>Alison</td>
                            <td>Agent</td>
                            <td>30</td>
                        </tr>
                        </tbody>
                    </table>
                </div>

            </section>

            <section id="keyed-output-handler">
                <div class="page-header">
                    <h2>2.1 KeyedOutputHandler</h2>
                </div>

                <h3>BeanMapOutputHandler</h3>

                <p><code>BeanMapOutputHandler</code> converts Query output into Map of Java Class. Column which would be treated as key is specified via Constructor</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// paramsList contains table found in the beginning of OutputHandler section
BeanMapOutputHandler&ltString, Character&gt handler = new BeanMapOutputHandler&ltString, Character&gt(Character.class, 0);

Map&ltString, Character&gt result = handler.handle(paramsList);

// result would contain map of rows (as Character class). result would contain:
// org.junit.Assert.assertArrayEquals(new Object[]{"jack", "sheriff", 36}, new Object[]{result.get("jack").getName(), result.get("jack").getOccupation(), result.get("jack").getAge()});
// org.junit.Assert.assertArrayEquals(new Object[]{"henry", "mechanic", 36}, new Object[]{result.get("henry").getName(), result.get("henry").getOccupation(), result.get("henry").getAge()});
// org.junit.Assert.assertArrayEquals(new Object[]{"alison", "agent", 30}, new Object[]{result.get("alison").getName(), result.get("alison").getOccupation(), result.get("alison").getAge()});</pre>

                <h3>KeyedOutputHandler</h3>

                <p><code>KeyedOutputHandler</code> converts Query output into Map of Maps. Column which would be treated as key is specified via Constructor</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// paramsList contains table found in the beginning of OutputHandler section
KeyedOutputHandler&ltString&gt handler = new KeyedOutputHandler&ltString&gt(0);

Map&ltString, Map&ltString, Object&gt&gt result = handler.handle(paramsList);

// result would contain map of rows (as map). result would contain:
//org.junit.Assert.assertArrayEquals(new Object[]{"jack", "sheriff", 36},
//		new Object[]{result.get("jack").get("name"), result.get("jack").get("occupation"), result.get("jack").get("age")});
//org.junit.Assert.assertArrayEquals(new Object[]{"henry", "mechanic", 36},
//		new Object[]{result.get("henry").get("name"), result.get("henry").get("occupation"), result.get("henry").get("age")});
//org.junit.Assert.assertArrayEquals(new Object[]{"alison", "agent", 30},
//		new Object[]{result.get("alison").get("name"), result.get("alison").get("occupation"), result.get("alison").get("age")});</pre>

            </section>

            <section id="base-output-handler">
                <div class="page-header">
                    <h2>2.2 BaseOutputHandler</h2>
                </div>

                <h3>ArrayOutputHandler</h3>

                <p><code>ArrayOutputHandler</code> converts Query output (first row) into Array of Object</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// paramsList contains table found in the beginning of OutputHandler section
Object[] result = new ArrayOutputHandler().handle(paramsList)

// result would contain first row(default): "jack", "sheriff", 36
// Assert.assertArrayEquals(new Object[]{"jack", "sheriff", 36}, result);
</pre>

                <h3>ArrayListOutputHandler</h3>

                <p><code>ArrayListOutputHandler</code> converts Query output into List of Array of Object(each line is represented as List element)</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// paramsList contains table found in the beginning of OutputHandler section
List&ltObject[]&gt result = new ArrayListOutputHandler().handle(paramsList);

// result would contain list of rows (as arrays). result would contain:
// Assert.assertArrayEquals(new Object[]{"jack", "sheriff", 36}, result.get(0));
// Assert.assertArrayEquals(new Object[]{"henry", "mechanic", 36}, result.get(1));
// Assert.assertArrayEquals(new Object[]{"alison", "agent", 30}, result.get(2));</pre>

                <h3>BeanOutputHandler</h3>

                <p><code>BeanOutputHandler</code> converts Query output (first row) into Java Class</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// paramsList contains table found in the beginning of OutputHandler section
BeanOutputHandler&ltCharacter&gt handler = new BeanOutputHandler&ltCharacter&gt(Character.class);

Character result = handler.handle(paramsList);

// result would contain first row converted into Character class
// org.junit.Assert.assertArrayEquals(new Object[]{"jack", "sheriff", 36}, new Object[]{result.getName(), result.getOccupation(), result.getAge()});</pre>

                <h3>BeanListOutputHandler</h3>

                <p><code>BeanListOutputHandler</code> converts Query output into List of Java Class(each line is represented as List element)</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// paramsList contains table found in the beginning of OutputHandler section
List&ltCharacter&gt result = new BeanListOutputHandler&ltCharacter&gt(Character.class).handle(paramsList);

// result would contain list of rows (as Character class). result would contain:
// Assert.assertArrayEquals(new Object[]{"jack", "sheriff", 36}, new Object[]{result.get(0).getName(), result.get(0).getOccupation(), result.get(0).getAge()});
// Assert.assertArrayEquals(new Object[]{"henry", "mechanic", 36}, new Object[]{result.get(1).getName(), result.get(1).getOccupation(), result.get(1).getAge()});
// Assert.assertArrayEquals(new Object[]{"alison", "agent", 30}, new Object[]{result.get(2).getName(), result.get(2).getOccupation(), result.get(2).getAge()});</pre>

                <h3>ColumnListOutputHandler</h3>

                <p><code>ColumnListOutputHandler</code> converts Query output Column (specified via Constructor) into List of Object(each line is represented as List element)</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// paramsList contains table found in the beginning of OutputHandler section
List&ltString&gt result = new ColumnListOutputHandler&ltString&gt(0).handle(paramsList);

// result would contain first column(0): "jack", "henry", "alison"
// Assert.assertArrayEquals(new Object[] {"jack", "henry", "alison"}, result.toArray());</pre>

                <h3>MapListOutputHandler</h3>

                <p><code>MapListOutputHandler</code> converts Query output into List of Maps(each line is represented as List element)</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// paramsList contains table found in the beginning of OutputHandler section
MapListOutputHandler handler = new MapListOutputHandler();

List&ltMap&ltString, Object&gt&gt result = handler.handle(paramsList);

// result would contain list of rows (as Map). result would contain:
//org.junit.Assert.assertArrayEquals(new Object[]{"jack", "sheriff", 36},
//       new Object[]{result.get(0).get("name"), result.get(0).get("occupation"), result.get(0).get("age")});
//org.junit.Assert.assertArrayEquals(new Object[]{"henry", "mechanic", 36},
//       new Object[]{result.get(1).get("name"), result.get(1).get("occupation"), result.get(1).get("age")});
//org.junit.Assert.assertArrayEquals(new Object[]{"alison", "agent", 30},
//       new Object[]{result.get(2).get("name"), result.get(2).get("occupation"), result.get(2).get("age")}); </pre>

                <h3>MapOutputHandler</h3>

                <p><code>MapOutputHandler</code> converts Query output (first row) into Map</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// paramsList contains table found in the beginning of OutputHandler section
MapOutputHandler handler = new MapOutputHandler();

Map&ltString, Object&gt result = handler.handle(paramsList);

// result would contain first row as Map: "jack", "sheriff", 36
//org.junit.Assert.assertArrayEquals(new Object[]{"jack", "sheriff", 36},
//		new Object[]{result.get("name"), result.get("occupation"), result.get("age")});</pre>

                <h3>RowCountOutputHandler</h3>

                <p><code>RowCountOutputHandler</code> returns number of rows updated. Useful during <code>update</code> invocation.</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
RowCountOutputHandler&ltInteger&gt handler = new RowCountOutputHandler&ltInteger&gt();
		  </pre>

                <h3>ScalarOutputHandler</h3>

                <p><code>ScalarOutputHandler</code> converts Query output Column (specified via Constructor) (first row) into Object</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// paramsList contains table found in the beginning of OutputHandler section
ScalarOutputHandler&ltString&gt handler = new ScalarOutputHandler&ltString&gt(0);

String result = handler.handle(paramsList);

// return would contain first row and first column(0).
// Assert.assertEquals("jack", result);</pre>

            </section>

            <section id="lazy-output-handler">
                <div class="page-header">
                    <h2>2.3 LazyOutputHandler</h2>
                </div>

                <h3>BeanLazyOutputHandler</h3>

                <p><code>BeanLazyOutputHandler</code> allows lazy reading of query output as sequence of Java classes</p>

                <p><code>BeanLazyOutputHandler</code> useful in cases when you have to fetch a lot of data, but not all of it will be actually needed.
                    For example if user searched for 100 pages but will be able to browse few pages only.</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// It is generally advised to use standard cached queries as all resource management is done by the system.

// During lazy query execution developer have to manually manage transactions (QueryRunnerService.commit/rollback) and manually close resources (LazyOutputHandler.close).
QueryRunnerService runner = MjdbcFactory.getQueryRunner(this.dataSource);

// lazy query execution can be done only in manual transaction mode.
runner.setTransactionManualMode(true);

...

// return as Bean List
BeanLazyOutputHandler&ltStudent&gt lazyBeanList = runner.query(input, new BeanLazyOutputHandler&ltStudent&gt(Student.class));

// iterate over Bean List
while (lazyBeanList.hasNext() == true) {
	// retrieve next element
	lazyBeanList.getNext() // returns Student class
}

// freeing all used resources. If not closed - might lead to resource leak and/or errors.
lazyBeanList.close();

// telling to finish current transaction(doesn't matter if it is update or just query) and free all the resources.
// if current transaction would be committed before LazyOutputHandler was closed - it might be no longer accessible and exception might be thrown.
runner.commit();</pre>

                <h3>BeanLazyScrollUpdateOutputHandler</h3>

                <p><code>BeanLazyScrollUpdateOutputHandler</code> allows lazy scrolling/updating of query output as sequence of Java classes</p>

                <p>For description of scrollable/updateable lazy output handlers please look at <a href="mjdbc-other-features.html#lazy-scroll-update">Lazy scroll/update support</a></p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// Please do not forget that all standard rules of LazyOutputHandlers still apply - using manual mode, closing resources and committing values (review BeanLazyOutputHandler example above).
...

// return as Bean List
BeanLazyScrollUpdateOutputHandler&ltStudent&gt lazyBeanList = runner.query(input, new BeanLazyScrollUpdateOutputHandler&ltStudent&gt(Student.class));

// iterate backwards over Bean List
while (lazyBeanList.hasPrev() == true) {
	// retrieve prev element
	lazyBeanList.hasPrev() // returns Student class
}

// move cursor to specified position
lazyBeanList.moveTo(newCursorPosition);
// move cursor relatively by specified amount of rows
lazyBeanList.moveRelative(moveCursorRelative);

// read value
lazyBeanList.getCurrent();

// updates current row
lazyBeanList.updateRow(student);

// inserts new row
lazyBeanList.insertRow(student);

...</pre>

                <h3>BeanLazyScrollOutputHandler</h3>

                <p><code>BeanLazyScrollOutputHandler</code> allows lazy scrolling (read-only) of query output as sequence of Java classes</p>

                <p>For description of scrollable/updateable lazy output handlers please look at <a href="mjdbc-other-features.html#lazy-scroll-update">Lazy scroll/update support</a></p>

                <h3>BeanLazyUpdateOutputHandler</h3>

                <p><code>BeanLazyUpdateOutputHandler</code> allows lazy updating (forward only) of query output as sequence of Java classes</p>

                <p>For description of scrollable/updateable lazy output handlers please look at <a href="mjdbc-other-features.html#lazy-scroll-update">Lazy scroll/update support</a></p>

                <hr class="bs-docs-separator">

                <h3>MapLazyOutputHandler</h3>

                <p><code>MapLazyOutputHandler</code> allows lazy reading of query output as sequence of Maps</p>

                <p><code>MapLazyOutputHandler</code> useful in cases when you have to fetch a lot of data, but not all of it will be actually needed.
                    For example if user searched for 100 pages but will be able to browse few pages only.</p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// It is generally advised to use standard cached queries as all resource management is done by the system.

// During lazy query execution developer have to manually manage transactions (QueryRunnerService.commit/rollback) and manually close resources (LazyOutputHandler.close).
QueryRunnerService runner = MjdbcFactory.getQueryRunner(this.dataSource);

// lazy query execution can be done only in manual transaction mode.
runner.setTransactionManualMode(true);

...

// return as Map List
MapLazyOutputHandler lazyMapList =  runner.query(input, new MapLazyOutputHandler());

// iterate over Map List
while (lazyMapList.hasNext() == true) {
	// retrieve next element
	lazyMapList.getNext() // returns Map
}

// freeing all used resources. If not closed - might lead to resource leak and/or errors.
lazyMapList.close();

// telling to finish current transaction(doesn't matter if it is update or just query) and free all the resources.
// if current transaction would be committed before LazyOutputHandler was closed - it might be no longer accessible and exception might be thrown.
runner.commit();</pre>

                <h3>MapLazyScrollUpdateOutputHandler</h3>

                <p><code>MapLazyScrollUpdateOutputHandler</code> allows lazy scrolling/updating of query output as sequence of Java maps</p>

                <p>For description of scrollable/updateable lazy output handlers please look at <a href="mjdbc-other-features.html#lazy-scroll-update">Lazy scroll/update support</a></p>

                <div class="bs-docs-example">
                    Example usage
                </div>
		  <pre class="prettyprint linenums">
// Please do not forget that all standard rules of LazyOutputHandlers still apply - using manual mode, closing resources and committing values (review MapLazyOutputHandler example above).
...

// return as Bean List
MapLazyScrollUpdateOutputHandler lazyMapList = runner.query(input, new MapLazyScrollUpdateOutputHandler());

// iterate backwards over Bean List
while (lazyMapList.hasPrev() == true) {
	// retrieve prev element
	lazyMapList.hasPrev() // returns map
}

// move cursor to specified position
lazyMapList.moveTo(newCursorPosition);
// move cursor relatively by specified amount of rows
lazyMapList.moveRelative(moveCursorRelative);

// read value
lazyMapList.getCurrent();

// updates current row
lazyMapList.updateRow(studentMap);

// inserts new row
lazyMapList.insertRow(studentMap);

...</pre>

                <h3>MapLazyScrollOutputHandler</h3>

                <p><code>MapLazyScrollOutputHandler</code> allows lazy scrolling (read-only) of query output as sequence of Java classes</p>

                <p>For description of scrollable/updateable lazy output handlers please look at <a href="mjdbc-other-features.html#lazy-scroll-update">Lazy scroll/update support</a></p>

                <h3>MapLazyUpdateOutputHandler</h3>

                <p><code>MapLazyUpdateOutputHandler</code> allows lazy updating (forward only) of query output as sequence of Java classes</p>

                <p>For description of scrollable/updateable lazy output handlers please look at <a href="mjdbc-other-features.html#lazy-scroll-update">Lazy scroll/update support</a></p>
            </section>

            <section id="xml-handler">
                <div class="page-header">
                    <h2>3. XML Handlers</h2>
                </div>

                <p>XML Handlers were created to allow execution of queries from external files. Main benefit comes from the fact that query and it's configuration (generate keys, output handler etc.) can be stored in external file and query change won't require rebuild/redeploy of the whole package</p>

                <p>Version 0.9.5 comes with support of XML handler with next features: query/update execution, any available output handler (inc. lazy), generate keys, control parameter count etc. Next features are planned to be implemented: call/batch execution, setting of statement/type handler per query, refresh mechanism in case of file change etc.</p>

                <p>Xml handlers utilize existing Midao JDBC guidelines and XML syntax is inspired by
                    <a href="http://mybatis.github.io/mybatis-3/sqlmap-xml.html">iBatis/MyBatis</a> project, but please be informed that differences between myBatis and Midao JDBC Xml Handlers are substantial as Midao JDBC is not an ORM library nor tries to be one. The goal behind Xml Handlers is to simplify query execution and allow ORM execution when needed.
                </p>
                <br/>

                <p>Example usage can be found below:</p>

                <div class="bs-docs-example">
                    Example of XML input/output handler (handling custom class)
                </div>
<pre class="prettyprint linenums">
String xmlContent = "&lt?xml version=\"1.0\"?&gt" +
    "&ltroot&gt" +
        "&ltquery id='org.midao.jdbc.examples.Student.findOne' outputHandler='BeanOutputHandler'&gt" +
            "SELECT name FROM students WHERE id = #{id,jdbcType=INTEGER,mode=in}" +
        "&lt/query&gt" +
    "&lt/root&gt";

// xml should be added to Repository before it can be executed
XmlRepositoryFactory.addAll(
    XmlRepositoryFactory.getDocument(new ByteArrayInputStream(
        xmlContent.getBytes()
    )
));

XmlInputOutputHandler&ltStudent&gt handler = new XmlInputOutputHandler&ltStudent&gt(Student.class, "findOne", 1);

// XML query execution
Student student = (Student) runner.execute(handler);
</pre>

                <div class="bs-docs-example">
                    Example of XML input/output handler (handling map)
                </div>
<pre class="prettyprint linenums">
String xmlContent = "&lt?xml version=\"1.0\"?&gt" +
    "&ltroot&gt" +
        "&ltquery id='findStudent' outputHandler='MapOutputHandler'&gt" +
            "SELECT name FROM students WHERE id = #{id,jdbcType=INTEGER,mode=in}" +
        "&lt/query&gt" +
    "&lt/root&gt";

// xml should be added to Repository before it can be executed
XmlRepositoryFactory.addAll(
    XmlRepositoryFactory.getDocument(new ByteArrayInputStream(
        xmlContent.getBytes()
    )
));

XmlInputOutputHandler handler = new XmlInputOutputHandler("findStudent", 1);

// XML query execution
Student student = (Student) runner.execute(handler);
</pre>

                <p>List of allowed commands:</p>
                <ul>
                    <li><code>query</code> - performs <code>query</code> invocation via <code>QueryRunnerService.query()</code></li>
                    <li><code>update</code> - performs <code>update</code> invocation via <code>QueryRunnerService.update()</code></li>
                </ul>

                <p>List of allowed parameters:</p>
                <ul>
                    <li><code>id</code> - Mandatory. In there you should specify query name. If query handles Bean - full bean name (inc. package) should be set as prefix to the name, example: <code>id='org.midao.jdbc.examples.Student.findOne'</code>.</li>
                    <li><code>outputHandler</code> - Optional. In there you should specify one of the <code><a href="http://midao.org/mjdbc-io-handlers.html#output-handler">OutputHandlers</a></code>. If nothing was set - <code>MapListOutputHandler</code> would be used by default.</li>
                    <li><code>generateKeys</code> - Optional. Accepts <code>true</code> value. If set - instructs JDBC to return generated keys.</li>
                    <li><code>generateKeysColumns</code> - Optional. If <code>generateKeys</code> is set "true" and you are using Oracle database - that field should be used to specify fields which are generated, example: <code>generateKeysColumns="ID,TRIGGER_GENERATED_COLUMN"</code></li>
                    <li><code>controlParamCount</code> - Optional. If you need to turn off parameter amount control (might be needed in rare cases) - you can set it via that parameter. Accepts values: <code>true/false</code>.</li>
                </ul>

                <p>List of allowed parameter (for example: <code>#{id}</code>) inline configuration:</p>
                <ul>
                    <li><code>jdbcType</code> - Optional. Allows setting types which are listed in <a href="http://midao.org/mjdbc/javadoc/org/midao/jdbc/core/MjdbcTypes.html">MjdbcTypes</a>. Example: <code>#{id,jdbcType=INTEGER}</code></li>
                    <li><code>mode</code> - Optional. Allows setting direction which are listed in <a href="http://midao.org/mjdbc/javadoc/org/midao/jdbc/core/handlers/model/QueryParameters.Direction.html">QueryParameters.Direction</a>. Example: <code>#{id,mode=in}</code></li>
                </ul>
            </section>


            <!-- Intense debate -->
            <section id="feedback">
                <div class="page-header">
                    <h1>Feedback</h1>
                </div>

                <p class="lead">Below you can provide feedback, suggestions, questions regarding information posted on current page</p>

                <script>
                    var idcomments_acct = '5ecab3490982db30c1c539bf485f65f2';
                    var idcomments_post_id;
                    var idcomments_post_url;
                </script>
                <span id="IDCommentsPostTitle" style="display:none"></span>
                <script type='text/javascript' src='http://www.intensedebate.com/js/genericCommentWrapperV2.js'></script>
            </section>

        </div>
    </div>

</div>

<!-- Footer
================================================== -->
<footer class="footer">
    <div class="container">
        <p>Designed and built based on Bootstrap</p>

        <p>Contact <a href="mailto:midao@midao.org">midao@midao.org</a> or <a target="_blank" href="http://twitter.com/midaoproject">@midaoproject</a></p>

        <ul class="footer-links">
            <li>
                <script src="http://platform.linkedin.com/in.js" type="text/javascript">
                    lang: en_US
                </script>
                <script type="IN/Share"></script>
            </li>
            <li class="muted">&middot;</li>
            <li>
                <a href="https://twitter.com/share" class="twitter-share-button" data-url="http://midao.org/home.html" data-text="Check Midao Project" data-via="midaoproject" data-count="none">Tweet</a>
                <script>!function (d, s, id) {
                    var js, fjs = d.getElementsByTagName(s)[0], p = /^http:/.test(d.location) ? 'http' : 'https';
                    if (!d.getElementById(id)) {
                        js = d.createElement(s);
                        js.id = id;
                        js.src = p + '://platform.twitter.com/widgets.js';
                        fjs.parentNode.insertBefore(js, fjs);
                    }
                }(document, 'script', 'twitter-wjs');</script>
            </li>
        </ul>

        <ul class="footer-links">
            <li><a target="_blank" href="https://github.com/pryzach/midao">GitHub</a></li>
            <li class="muted">&middot;</li>
            <li><a target="_blank" href="https://github.com/pryzach/midao/issues">Issues / Questions / Feature request</a></li>
            <li class="muted">&middot;</li>
            <li><a target="_blank" href="https://github.com/pryzach/midao/blob/master/CHANGELOG.md">Change log</a></li>
        </ul>
    </div>
</footer>


<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script type="text/javascript" src="http://platform.twitter.com/widgets.js"></script>
<script src="js/jquery.js"></script>
<script src="js/bootstrap-transition.js"></script>
<script src="js/bootstrap-alert.js"></script>
<script src="js/bootstrap-modal.js"></script>
<script src="js/bootstrap-dropdown.js"></script>
<script src="js/bootstrap-scrollspy.js"></script>
<script src="js/bootstrap-tab.js"></script>
<script src="js/bootstrap-tooltip.js"></script>
<script src="js/bootstrap-popover.js"></script>
<script src="js/bootstrap-button.js"></script>
<script src="js/bootstrap-collapse.js"></script>
<script src="js/bootstrap-carousel.js"></script>
<script src="js/bootstrap-typeahead.js"></script>
<script src="js/bootstrap-affix.js"></script>

<script src="js/holder/holder.js"></script>
<script src="js/google-code-prettify/prettify.js"></script>

<script src="js/application.js"></script>

</body>
</html>
